~ chicken-core (master) /manual/Module (chicken number-vector)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken number-vector)56Homogeneous numeric vector datatypes. This module provides a superset7of [[http://srfi.schemers.org/srfi-4/srfi-4.html|SRFI-4]]. The8module [[Module srfi-4|srfi-4]] is also available for compatibility reasons.910When loaded, the feature identifier {{srfi-4}} is defined.1112=== CHICKEN implementation specifics and extensions to SRFI-41314* Procedures for [[Module (chicken bytevector)|bytevector]] conversion, subvectors and vector I/O are provided.15* SRFI-17 setters for {{XXXvector-ref}} are defined.16* Constructors allow allocating the storage in non garbage collected memory.17* Vectors for 64 and 128-bit complex numbers are provided.1819This module provides a set of datatypes for vectors whose elements are20of the same numeric type (signed or unsigned exact integer or inexact21real of a given precision). These datatypes support operations analogous22to the Scheme vector type, but they are distinct datatypes. An external23representation is specified which must be supported by the {{read}} and24{{write}} procedures and by the program parser (i.e. programs can contain25references to literal homogeneous vectors).2627=== Datatypes2829There are 8 datatypes of exact integer homogeneous vectors (which will be30called integer vectors):3132<table>33<tr><th>Datatype</th><th>Type of elements</th></tr>34<tr><td>{{s8vector}}</td><td>signed exact integer in the range -(2^7) to (2^7)-1</td></tr>35<tr><td>{{u8vector}}</td><td>unsigned exact integer in the range 0 to (2^8)-1</td></tr>36<tr><td>{{s16vector}}</td><td>signed exact integer in the range -(2^15) to (2^15)-1</td></tr>37<tr><td>{{u16vector}}</td><td>unsigned exact integer in the range 0 to (2^16)-1</td></tr>38<tr><td>{{s32vector}}</td><td>signed exact integer in the range -(2^31) to (2^31)-1</td></tr>39<tr><td>{{u32vector}}</td><td>unsigned exact integer in the range 0 to (2^32)-1</td></tr>40<tr><td>{{s64vector}}</td><td>signed exact integer in the range -(2^31) to (2^31)-1</td></tr>41<tr><td>{{u64vector}}</td><td>unsigned exact integer in the range 0 to (2^64)-1</td></tr>42<tr><td>{{s64vector}}</td><td>signed exact integer in the range -(2^63) to (2^63)-1</td></tr>43<tr><td>{{u64vector}}</td><td>unsigned exact integer in the range 0 to (2^64)-1</td></tr></table>4445There are 2 datatypes of inexact real homogeneous vectors (which will be46called float vectors):4748<table>49<tr><th>Datatype</th><th>Type of elements</th></tr>50<tr><td>{{f32vector}}</td><td>inexact real</td></tr>51<tr><td>{{f64vector}}</td><td>inexact real</td></tr></table>5253The only difference between the two float vector types is that54{{f64vector}}s preserve at least as much precision as {{f32vector}}s.5556And there are two datatypes of inexact complex homogeneous vectors (which will be called complex vectors):5758<table>59<tr><th>Datatype</th><th>Type of elements</th></tr>60<tr><td>{{c64vector}}</th><th>inexact complex, typically 64 bits</td></tr>61<tr><td>{{c128vector}}</th><th>inexact complex, typically 128 bits</td></tr>62</table>6364Each homogeneous vector datatype has an external representation which65is supported by the {{read}} and {{write}} procedures and by the program66parser. Each datatype also has a set of associated predefined procedures67analogous to those available for Scheme's heterogeneous vectors.6869=== External representation7071<read>#u8</read><br>72<read>#u16</read><br>73<read>#u32</read><br>74<read>#s8</read><br>75<read>#s16</read><br>76<read>#s32</read><br>77<read>#f32</read><br>78<read>#f64</read><br>79<read>#c64</read><br>80<read>#c128</read><br>8182The external representation of instances of the datatype {{XXXvector}}83is {{#XXX( ...elements... )}}.8485For example,8687 #u8(0 #e1e2 #xff)}} ; a {{u8vector}} of length 3 containing 0, 100, 25588 #f64(-1.5) ; a {{f64vector}} of length 1 containing -1.5.8990This external representation is also available in program source code. For example,9192 (set! x '#u8(1 2 3))9394will set {{x}} to the object {{#u8(1 2 3)}}. Since CHICKEN 4.9.0, literal homogeneous vectors do not have to be quoted. Homogeneous vectors can appear in quasiquotations but must not contain {{unquote}} or {{unquote-splicing}} forms. ''I.e.'',9596 `(,x #u8(1 2)) ; legal97 `#u8(1 ,x 2) ; illegal9899Elements may also be characters, lists, number vectors or strings, in that case they are interpreted100as a sequence of numerical character codes. For example,101102 '#u8(#\x7f "EL" #\F 2 1)103104is equivalent to105106 '#u8(#\x7f #\x45 #\x4c #\x46 2 1)107108Character literals inside numeric vectors expand into the UTF-8 sequence of109the characters they represent, for strings the contained characters110are interpreted as UTF-8. Embedded bytevectors or numerical vectors are111spliced directly into the result, without further translation. Lists are112spliced as well, recursively, so:113114 '#u8(1 #;header (2 #;lengths (3 4) #u16(#xABCD)) )115116will result in117118 #u8(1 2 3 4 #xCD #xAB)119120on a little endian machine.121122Note that {{#u8"..."}} can be used as an abbreviation for the special case123{{#u8("...")}}.124125=== Predicates126127<procedure>(u8vector? OBJ)</procedure><br>128<procedure>(s8vector? OBJ)</procedure><br>129<procedure>(u16vector? OBJ)</procedure><br>130<procedure>(s16vector? OBJ)</procedure><br>131<procedure>(u32vector? OBJ)</procedure><br>132<procedure>(s32vector? OBJ)</procedure><br>133<procedure>(u64vector? OBJ)</procedure><br>134<procedure>(s64vector? OBJ)</procedure><br>135<procedure>(f32vector? OBJ)</procedure><br>136<procedure>(f64vector? OBJ)</procedure><br>137<procedure>(c64vector? OBJ)</procedure><br>138<procedure>(c128vector? OBJ)</procedure><br>139140Return {{#t}} if {{obj}} is an object of the specified type or {{#f}} if not.141142<procedure>(number-vector? OBJ)</procedure>143144Return {{#t}} if {{obj}} is a number vector, {{#f}} if not. A "number vector" is any of the homogeneous number vector types defined by SRFI-4, ie it's one of {{u8vector}}, {{s8vector}}, {{u16vector}}, {{s16vector}}, {{u32vector}}, {{s32vector}}, {{u64vector}}, {{s64vector}}, {{f32vector}}, {{f64vector}}, {{c64vector}} or {{c128vector}}.145146147=== Constructors148149<procedure>(make-u8vector N [U8VALUE NONGC FINALIZE])</procedure><br>150<procedure>(make-s8vector N [S8VALUE NONGC FINALIZE])</procedure><br>151<procedure>(make-u16vector N [U16VALUE NONGC FINALIZE])</procedure><br>152<procedure>(make-s16vector N [S16VALUE NONGC FINALIZE])</procedure><br>153<procedure>(make-u32vector N [U32VALUE NONGC FINALIZE])</procedure><br>154<procedure>(make-s32vector N [S32VALUE NONGC FINALIZE])</procedure><br>155<procedure>(make-u64vector N [U64VALUE NONGC FINALIZE])</procedure><br>156<procedure>(make-s64vector N [S64VALUE NONGC FINALIZE])</procedure><br>157<procedure>(make-f32vector N [F32VALUE NONGC FINALIZE])</procedure><br>158<procedure>(make-f64vector N [F64VALUE NONGC FINALIZE])</procedure><br>159<procedure>(make-c64vector N [C64VALUE NONGC FINALIZE])</procedure><br>160<procedure>(make-c128vector N [C128VALUE NONGC FINALIZE])</procedure><br>161162Return a newly-allocated SRFI-4 homogeneous number vector of length N.163164If the optional fill VALUE is specified, it specifies the initial165value for each slot in the vector. If not, the content of the vector166is unspecified but individual elements of the vector are guaranteed to167be in the range of values permitted for that type of vector.168169The type of the fill value must be compatible with the elements of the170vector datatype. It is an error if otherwise -- for example, if an171inexact integer is passed to {{make-u8vector}}.172173On CHICKEN, these procedures have been extended to allow allocating174the storage in non-garbage collected memory, as follows:175176The optional arguments {{NONGC}} and {{FINALIZE}} define whether the177vector should be allocated in a memory area not subject to garbage178collection and whether the associated storage should be automatically179freed (using finalization) when there are no references from Scheme180variables and data. {{NONGC}} defaults to {{#f}} (the vector will be181located in normal garbage collected memory) and {{FINALIZE}} defaults182to {{#t}}. Note that the {{FINALIZE}} argument is only used when183{{NONGC}} is true.184185<procedure>(u8vector U8VALUE ...)</procedure><br>186<procedure>(s8vector S8VALUE ...)</procedure><br>187<procedure>(u16vector U16VALUE ...)</procedure><br>188<procedure>(s16vector S16VALUE ...)</procedure><br>189<procedure>(u32vector U32VALUE ...)</procedure><br>190<procedure>(s32vector S32VALUE ...)</procedure><br>191<procedure>(u64vector U64VALUE ...)</procedure><br>192<procedure>(s64vector S64VALUE ...)</procedure><br>193<procedure>(f32vector F32VALUE ...)</procedure><br>194<procedure>(f64vector F64VALUE ...)</procedure><br>195<procedure>(c64vector C64VALUE ...)</procedure><br>196<procedure>(c128vector C128VALUE ...)</procedure><br>197198Return a newly-allocated SRFI-4 homogeneous number vector of the specified199type, composed of the arguments.200201=== Length202203<procedure>(u8vector-length U8VECTOR)</procedure><br>204<procedure>(s8vector-length S8VECTOR)</procedure><br>205<procedure>(u16vector-length U16VECTOR)</procedure><br>206<procedure>(s16vector-length S16VECTOR)</procedure><br>207<procedure>(u32vector-length U32VECTOR)</procedure><br>208<procedure>(s32vector-length S32VECTOR)</procedure><br>209<procedure>(u64vector-length U64VECTOR)</procedure><br>210<procedure>(s64vector-length S64VECTOR)</procedure><br>211<procedure>(f32vector-length F32VECTOR)</procedure><br>212<procedure>(f64vector-length F64VECTOR)</procedure><br>213<procedure>(c64vector-length C64VECTOR)</procedure><br>214<procedure>(c128vector-length C128VECTOR)</procedure><br>215216Returns the length of the SRFI-4 homogeneous number VECTOR.217218=== Getters219220<procedure>(u8vector-ref U8VECTOR I)</procedure><br>221<procedure>(s8vector-ref S8VECTOR i)</procedure><br>222<procedure>(u16vector-ref U16VECTOR I)</procedure><br>223<procedure>(s16vector-ref S16VECTOR I)</procedure><br>224<procedure>(u32vector-ref U32VECTOR I)</procedure><br>225<procedure>(s32vector-ref S32VECTOR I)</procedure><br>226<procedure>(u64vector-ref U64VECTOR I)</procedure><br>227<procedure>(s64vector-ref S64VECTOR I)</procedure><br>228<procedure>(f32vector-ref F32VECTOR I)</procedure><br>229<procedure>(f64vector-ref F64VECTOR I)</procedure><br>230<procedure>(c64vector-ref C64VECTOR I)</procedure><br>231<procedure>(c128vector-ref C128VECTOR I)</procedure><br>232233Return the value of the ''i''th element of the SRFI-4 homogeneous234number vector, where {{I}} is a nonnegative exact integer less235than the length of the vector.236237=== Setters238239<procedure>(u8vector-set! U8VECTOR I U8VALUE)</procedure><br>240<procedure>(s8vector-set! S8VECTOR I S8VALUE)</procedure><br>241<procedure>(u16vector-set! U16VECTOR I U16VALUE)</procedure><br>242<procedure>(s16vector-set! S16VECTOR I S16VALUE)</procedure><br>243<procedure>(u32vector-set! U32VECTOR I U32VALUE)</procedure><br>244<procedure>(s32vector-set! S32VECTOR I S32VALUE)</procedure><br>245<procedure>(u64vector-set! U64VECTOR I U64VALUE)</procedure><br>246<procedure>(s64vector-set! S64VECTOR I S64VALUE)</procedure><br>247<procedure>(f32vector-set! F32VECTOR I F32VALUE)</procedure><br>248<procedure>(f64vector-set! F64VECTOR I F64VALUE)</procedure><br>249<procedure>(c64vector-set! C64VECTOR I C64VALUE)</procedure><br>250<procedure>(c128vector-set! C128VECTOR I C128VALUE)</procedure><br>251252Set the {{i}}th element of the SRFI-4 homogeneous number VECTOR to253VALUE. {{I}} is a nonnegative exact integer less than the length of254the vector and VALUE must be the same type as the elements of the255vector datatype.256257Additionally, SRFI-17 setters are defined on all {{xxxvector-ref}}258procedures. For example, to set the {{i}}th element of SRFI-4259{{u8vector}} to {{u8value}}:260261 (set! (u8vector-ref u8vector i) u8value)262263=== Conversions264265<procedure>(u8vector->list U8VECTOR)</procedure><br>266<procedure>(s8vector->list S8VECTOR)</procedure><br>267<procedure>(u16vector->list U16VECTOR)</procedure><br>268<procedure>(s16vector->list S16VECTOR)</procedure><br>269<procedure>(u32vector->list U32VECTOR)</procedure><br>270<procedure>(s32vector->list S32VECTOR)</procedure><br>271<procedure>(u64vector->list U64VECTOR)</procedure><br>272<procedure>(s64vector->list S64VECTOR)</procedure><br>273<procedure>(f32vector->list F32VECTOR)</procedure><br>274<procedure>(f64vector->list F64VECTOR)</procedure><br>275<procedure>(c64vector->list C64VECTOR)</procedure><br>276<procedure>(c128vector->list C128VECTOR)</procedure><br>277278Return a list consisting of the elements of SRFI-4 homogeneous number279VECTOR.280281<procedure>(list->u8vector U8LIST)</procedure><br>282<procedure>(list->s8vector S8LIST)</procedure><br>283<procedure>(list->u16vector U16LIST)</procedure><br>284<procedure>(list->s16vector S16LIST)</procedure><br>285<procedure>(list->u32vector U32LIST)</procedure><br>286<procedure>(list->s32vector S32LIST)</procedure><br>287<procedure>(list->u64vector U64LIST)</procedure><br>288<procedure>(list->s64vector S64LIST)</procedure><br>289<procedure>(list->f32vector F32LIST)</procedure><br>290<procedure>(list->f64vector F64LIST)</procedure><br>291<procedure>(list->c64vector C64LIST)</procedure><br>292<procedure>(list->c128vector C128LIST)</procedure><br>293294Return a newly-allocated SRFI-4 homogeneous number VECTOR consisting295of the elements of LIST. Each element of LIST must be compatible296with the datatype of VECTOR.297298299=== Blob conversions300301As a number vector is basically just a [[Module (chicken bytevector)|bytevector]]302wrapped into a record type,303there are several procedures which can convert between bytevectors and304number vectors.305306Note that built-in bytevectors are identical to u8vectors.307308<procedure>(s8vector->bytevector S8VECTOR)</procedure><br>309<procedure>(u16vector->bytevector U16VECTOR)</procedure><br>310<procedure>(s16vector->bytevector S16VECTOR)</procedure><br>311<procedure>(u32vector->bytevector U32VECTOR)</procedure><br>312<procedure>(s32vector->bytevector S32VECTOR)</procedure><br>313<procedure>(u64vector->bytevector U64VECTOR)</procedure><br>314<procedure>(s64vector->bytevector S64VECTOR)</procedure><br>315<procedure>(f32vector->bytevector F32VECTOR)</procedure><br>316<procedure>(f64vector->bytevector F64VECTOR)</procedure><br>317<procedure>(c64vector->bytevector C64VECTOR)</procedure><br>318<procedure>(c128vector->bytevector C128VECTOR)</procedure><br>319<procedure>(u8vector->bytevector/shared U8VECTOR)</procedure><br>320<procedure>(s8vector->bytevector/shared S8VECTOR)</procedure><br>321<procedure>(u16vector->bytevector/shared U16VECTOR)</procedure><br>322<procedure>(s16vector->bytevector/shared S16VECTOR)</procedure><br>323<procedure>(u32vector->bytevector/shared U32VECTOR)</procedure><br>324<procedure>(s32vector->bytevector/shared S32VECTOR)</procedure><br>325<procedure>(u64vector->bytevector/shared U64VECTOR)</procedure><br>326<procedure>(s64vector->bytevector/shared S64VECTOR)</procedure><br>327<procedure>(f32vector->bytevector/shared F32VECTOR)</procedure><br>328<procedure>(f64vector->bytevector/shared F64VECTOR)</procedure><br>329<procedure>(c64vector->bytevector/shared C64VECTOR)</procedure><br>330<procedure>(c128vector->bytevector/shared C128VECTOR)</procedure><br>331332Each of these procedures return the contents of the given vector as a333'packed' bytevector. The byte order in that vector is platform-dependent334(for example little-endian on an '''Intel''' processor). The335{{/shared}} variants return a bytevector that shares memory with the336contents of the vector, the others will copy the contents of the337vector's internal bytevector object.338339<procedure>(bytevector->s8vector BYTEVECTOR)</procedure><br>340<procedure>(bytevector->u16vector BYTEVECTOR)</procedure><br>341<procedure>(bytevector->s16vector BYTEVECTOR)</procedure><br>342<procedure>(bytevector->u32vector BYTEVECTOR)</procedure><br>343<procedure>(bytevector->s32vector BYTEVECTOR)</procedure><br>344<procedure>(bytevector->u64vector BYTEVECTOR)</procedure><br>345<procedure>(bytevector->s64vector BYTEVECTOR)</procedure><br>346<procedure>(bytevector->f32vector BYTEVECTOR)</procedure><br>347<procedure>(bytevector->f64vector BYTEVECTOR)</procedure><br>348<procedure>(bytevector->c64vector BYTEVECTOR)</procedure><br>349<procedure>(bytevector->c128vector BYTEVECTOR)</procedure><br>350<procedure>(bytevector->s8vector/shared BYTEVECTOR)</procedure><br>351<procedure>(bytevector->u16vector/shared BYTEVECTOR)</procedure><br>352<procedure>(bytevector->s16vector/shared BYTEVECTOR)</procedure><br>353<procedure>(bytevector->u32vector/shared BYTEVECTOR)</procedure><br>354<procedure>(bytevector->s32vector/shared BYTEVECTOR)</procedure><br>355<procedure>(bytevector->u64vector/shared BYTEVECTOR)</procedure><br>356<procedure>(bytevector->s64vector/shared BYTEVECTOR)</procedure><br>357<procedure>(bytevector->f32vector/shared BYTEVECTOR)</procedure><br>358<procedure>(bytevector->f64vector/shared BYTEVECTOR)</procedure><br>359<procedure>(bytevector->c64vector/shared BYTEVECTOR)</procedure><br>360<procedure>(bytevector->c128vector/shared BYTEVECTOR)</procedure><br>361362Each of these procedures return a vector where the argument {{BYTEVECTOR}}363is taken as a 'packed' representation of the contents of the364vector. The {{/shared}} variants return a vector that shares memory365with the contents of the bytevector, the others will copy the bytevector.366367=== Subvectors368369<procedure>(subu8vector U8VECTOR FROM TO)</procedure><br>370<procedure>(subu16vector U16VECTOR FROM TO)</procedure><br>371<procedure>(subu32vector U32VECTOR FROM TO)</procedure><br>372<procedure>(subu64vector U32VECTOR FROM TO)</procedure><br>373<procedure>(subs8vector S8VECTOR FROM TO)</procedure><br>374<procedure>(subs16vector S16VECTOR FROM TO)</procedure><br>375<procedure>(subs32vector S32VECTOR FROM TO)</procedure><br>376<procedure>(subs64vector S32VECTOR FROM TO)</procedure><br>377<procedure>(subf32vector F32VECTOR FROM TO)</procedure><br>378<procedure>(subf64vector F64VECTOR FROM TO)</procedure><br>379<procedure>(subc64vector C64VECTOR FROM TO)</procedure><br>380<procedure>(subc128vector C128VECTOR FROM TO)</procedure><br>381382Creates a fresh number vector of the same type as the argument vector383with the elements at the positions {{FROM}} up to but not including384{{TO}}.385386=== Release number vectors allocated in static memory387388<procedure>(release-number-vector NVECTOR)</procedure>389390Release the storage of a SRFI-4 vector that was allocated in391non-garbage collected memory (for example using the {{NONGC}} argument392for one of the {{make-XXXvector}} constructor procedures). The effect393of calling this procedure with a number vector allocated in normal394garbage collected memory is undefined.395396397---398Previous: [[Module (chicken type)]]399400Next: [[Interface to external functions and variables]]401